home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-01 / sefx10.zip / SEFX.DOC < prev    next >
Text File  |  1992-02-20  |  36KB  |  1,526 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.                Sefx
  13.  
  14.  
  15.                C Language Sound Effects Library
  16.  
  17.                Version 1.0
  18.  
  19.                20 Feb 92
  20.  
  21.                Copyright (c) 1992  Bri Productions
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.                                    1
  62.        Table of Contents
  63.  
  64.  
  65.  
  66.        Introduction
  67.  
  68.                Acknowledgments.........................4
  69.  
  70.                General Description.....................4
  71.  
  72.                Disclaimer..............................4
  73.  
  74.                Registration............................4
  75.  
  76.                Contacting the Author...................5
  77.  
  78.                Terminology.............................5
  79.  
  80.                A typedef...............................5
  81.  
  82.  
  83.        Control Functions
  84.  
  85.                Description.............................6
  86.  
  87.                SndOpen.................................7
  88.  
  89.                SndClose................................8
  90.  
  91.                SndLen..................................9
  92.  
  93.                SndTbase...............................10
  94.  
  95.                SndFlush...............................11
  96.  
  97.                SndHold................................12
  98.  
  99.                SndTerm................................13
  100.  
  101.  
  102.        Sound Generation Functions
  103.  
  104.                Description............................14
  105.  
  106.                SndTone................................15
  107.  
  108.                SndPause...............................16
  109.  
  110.                SndString..............................17
  111.  
  112.                SndTrill...............................18
  113.  
  114.                SndSlide...............................19
  115.  
  116.                SndPulse...............................20
  117.  
  118.  
  119.  
  120.  
  121.  
  122.                                    2
  123.        Miscellaneous
  124.  
  125.                SndMs..................................21
  126.  
  127.  
  128.  
  129.  
  130.        Appendix A - Things to look out for............22
  131.  
  132.  
  133.        Appendix B - Musical notes.....................23
  134.  
  135.  
  136.        Appendix C - Sound queue usage.................24
  137.  
  138.  
  139.        Appendix D - Registration form.................25
  140.  
  141.  
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.                                    3
  184.        Acknowledgments.
  185.  
  186.        I would like to thank Earl Jensen for technical review and
  187.        advice, James Garcia for musical information and Margaret
  188.        Carlsen for proof reading this documentation.
  189.  
  190.  
  191.  
  192.        General Description.
  193.  
  194.        Sefx is a C language timer-driven sound effects library for IBM
  195.        and compatible computers. Sefx is compatible with most if not
  196.        all DOS based C compilers.
  197.  
  198.        All the sound generated by Sefx is generated in the background.
  199.        This fact allows the program to continue with other operations
  200.        while the sound is generated.
  201.  
  202.  
  203.        Some of Sefx's features are:
  204.  
  205.        ∙ Generates sound simultaneously to other operations
  206.        ∙ Produces frequencies from 19 to 20,000+ hertz
  207.        ∙ Time bases of 54.9, 27.5, 13.7 and 6.9 milliseconds
  208.        ∙ Changes frequency up to 145 time per second
  209.        ∙ Adjustable sound queue as large as 65532 bytes
  210.        ∙ Sound queue is handled internally
  211.        ∙ Written in assembly language for optimum speed and efficiency.
  212.  
  213.  
  214.  
  215.        DISCLAIMER.
  216.  
  217.        Sefx is provided AS IS. Bri Productions specifically disclaims
  218.        any and all warranties, expressed or implied, including fitness
  219.        for a particular purpose. Use this product at your own risk.
  220.  
  221.  
  222.  
  223.        Registration.
  224.  
  225.        Sefx is a user supported software product. Distribution of
  226.        this product, unaltered and without charge, is encouraged. If
  227.        you find this product useful, you are encouraged to register
  228.        your copy. This allows Bri Productions to continue to provide
  229.        support low cost, high quality shareware.
  230.  
  231.        The registration fee is $20.00 US dollars and includes libraries
  232.        for small, medium, compact and large memory models and complete
  233.        source code. A registration form is provided in Appendix D.
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.                                    4
  245.        Contacting the author.
  246.  
  247.        Bri Productions may be contacted by any of the following means:
  248.  
  249.        CompuServe      -       76635,2246
  250.        U.S. mail       -       Bri Productions
  251.                                P.O.Box 7121
  252.                                Fremont, CA 94537-7121
  253.  
  254.        CompuServe is a trademark of CompuServe Inc.
  255.  
  256.  
  257.        Terminology
  258.  
  259.        This section is intended to define the terminology used in this
  260.        documentation and clarify any ambiguities thereof.
  261.  
  262.        A 'tone' consists of a single frequency and a 'duration'. A
  263.        'pause' is the same in all respects as a 'tone' except for the
  264.        absents of a frequency. It can also be defined as a 'tone' with
  265.        a frequency of zero.
  266.  
  267.        A 'sound' is one or more 'tones' and/or 'pauses' put together
  268.        to produce the desired results. ie. trill, slide, string, etc.
  269.        A 'sound' may consist of only one 'tone' or 'pause'. Each Sefx
  270.        sound generation function generates exactly one sound.
  271.  
  272.        The 'time base' refers to the length of time of one 'tic' which
  273.        is the basic unit of time used by the Sefx sound generating
  274.        functions. A new 'tone' or 'pause' may be loaded as often as
  275.        once per 'tic'. Hence the frequency may be changed as often
  276.        as the value of the 'time base'.
  277.  
  278.        The 'duration' of a 'tone' is the number of 'tics' (and hence
  279.        the length of time) it will last.
  280.  
  281.           Examples:
  282.  
  283.              A 'tone' with a 'duration' of two 'tics', when the
  284.              'time base' is set to MEDium (27.5ms), will last 55
  285.              milliseconds.
  286.  
  287.              A 'sound' consisting of a 'tone' with a 'duration' of of
  288.              two 'tics', a 'pause' with a 'duration' of one 'tic'
  289.              followed by another tone with a 'duration' of three 'tics'
  290.              when the 'time base' is set to HIGH (13.7ms), will last
  291.              82.2 milliseconds.
  292.  
  293.  
  294.        A typedef
  295.  
  296.        You will see the data type 'TONE' throughout the Sefx library.
  297.        TONE is a structure, defined in sefx.h, used for storing
  298.        frequency/duration pairs. This type is used mainly by the
  299.        function SndString. The fields are defined as follows:
  300.  
  301.                    typedef struct{
  302.                       int freq;         /* frequency */
  303.                       int durtn;        /* duration  */
  304.                       }TONE;
  305.                                    5
  306.         Control Functions
  307.  
  308.        Before sound can be generated, a call to SndOpen must be made
  309.        to initialize Sefx. SndOpen will also allocate memory for a sound
  310.        queue. Sounds are then loaded into the sound queue and played in
  311.        sequence
  312.  
  313.        Prior to program's termination, a call to SndClose must be made
  314.        to undo SndOpen. Failing to call SndClose prior to a program's
  315.        termination will cause the computer to lock up requiring a
  316.        reboot.
  317.  
  318.        Other control functions are available for manipulating and
  319.        procuring the status of the sound queue. The sound queue can
  320.        be flushed at any time with SndFlush. SndTerm terminates the
  321.        current sound while SndHold will put all sound on hold. The
  322.        number of bytes currently residing in the sound queue is available
  323.        through SndLen.
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.                                    6
  367.        ----------------------------------------------------------------
  368.        SndOpen
  369.        ----------------------------------------------------------------
  370.  
  371.        Function
  372.  
  373.              Initializes the timer and interrupt handler and allocates
  374.              memory for the sound queue.
  375.  
  376.  
  377.        Syntax
  378.  
  379.              #include "sefx.h"
  380.              int SndOpen(unsigned Qsize, int tbase);
  381.  
  382.  
  383.        Parameters
  384.  
  385.              Qsize - Size of the sound queue in bytes. The number
  386.                      of bytes required for a sound varies depending
  387.                      on the sound. This value will be rounded down
  388.                      so that it is even multiple of 4 bytes.
  389.  
  390.              tbase - Time base. This value determines the length of
  391.                      time of one tic and subsequently how often the
  392.                      frequency can be changed. Possibilities are:
  393.  
  394.                         LOW    (3) - 54.9 milliseconds
  395.                         MED    (2) - 27.5 milliseconds
  396.                         HIGH   (1) - 13.7 milliseconds
  397.                         ULTRA  (0) -  6.9 milliseconds
  398.  
  399.  
  400.        Remarks
  401.  
  402.              SndOpen initializes the timer chip, installs the
  403.              timer interrupt handler, allocates memory for the
  404.              sound queue and sets the time base.
  405.  
  406.              The time base determines how long one tic will be. Since
  407.              a new tone can be loaded as often as once per tic, this
  408.              value also determines how often the frequency can be
  409.              changed.
  410.  
  411.              After a call to SndOpen, a subsequent call to SndClose
  412.              must be made prior to the program's termination.
  413.  
  414.  
  415.        Return value
  416.  
  417.              SndOpen returns a zero if no errors occur, or non
  418.              zero on an error. Constants are defined in sefx.h
  419.              as follows:
  420.  
  421.                      NOERR       (0) - no errors
  422.                      OPENED      (1) - Sefx already opened
  423.                      MALLOC_ERR  (4) - queue allocation error
  424.  
  425.  
  426.  
  427.                                    7
  428.        See also
  429.  
  430.              SndClose SndTbase
  431.  
  432.  
  433.        Example
  434.  
  435.              Initialize Sefx, allocate a 1023 byte sound queue and
  436.              set the time base to MEDium resolution.
  437.  
  438.              #define  QSIZE     1024
  439.              {
  440.              int rv;
  441.  
  442.                 rv = SndOpen(QSIZE, MED);
  443.                 if(rv)
  444.                 {
  445.  
  446.                    ... error handler
  447.  
  448.                 }
  449.  
  450.  
  451.  
  452.        ----------------------------------------------------------------
  453.        SndClose
  454.        ----------------------------------------------------------------
  455.  
  456.        Function
  457.  
  458.              Restores the timer and timer interrupt, and releases the
  459.              sound queue from memory.
  460.  
  461.  
  462.        Syntax
  463.  
  464.              #include "sefx.h"
  465.              void SndClose(void);
  466.  
  467.  
  468.        Remarks
  469.  
  470.              SndClose restores the timer interrupt vector and the
  471.              timer chip to normal, and releases the memory allocated
  472.              for the sound queue.
  473.  
  474.              A call to SndClose is required prior to the program's
  475.              termination.
  476.  
  477.  
  478.        See also
  479.  
  480.              SndOpen
  481.  
  482.  
  483.  
  484.  
  485.  
  486.  
  487.  
  488.                                    8
  489.        Example
  490.  
  491.              Restore the interrupt vector and free the sound queue
  492.              prior to termination
  493.  
  494.              {
  495.  
  496.                 ... closing code
  497.  
  498.                 SndClose();
  499.              }
  500.  
  501.  
  502.  
  503.        ----------------------------------------------------------------
  504.        SndLen
  505.        ----------------------------------------------------------------
  506.  
  507.        Function
  508.  
  509.              Determines how many bytes are currently occupying the
  510.              sound queue.
  511.  
  512.  
  513.        Syntax
  514.  
  515.              #include "sefx.h"
  516.              unsigned SndLen(void);
  517.  
  518.  
  519.        Remarks
  520.  
  521.              SndLen determines how many bytes are currently occupying
  522.              the sound queue. The value is a direct representation
  523.              of how full the sound queue actually is and does not
  524.              necessarily represent how much time is left in the queue.
  525.  
  526.  
  527.        Return value
  528.  
  529.              SndLen returns the number of bytes currently residing in
  530.              the sound queue.
  531.  
  532.  
  533.        See also
  534.  
  535.              SndFlush SndHold SndTerm
  536.  
  537.  
  538.  
  539.  
  540.  
  541.  
  542.  
  543.  
  544.  
  545.  
  546.  
  547.  
  548.  
  549.                                    9
  550.        Example
  551.  
  552.              Check if there is room for 10 more bytes in the sound
  553.              queue.
  554.  
  555.              #define THRESH        512
  556.              #define SndThresh()   (SndLen() < THRESH)
  557.              {
  558.                 if(SndThresh())
  559.                 {
  560.  
  561.                    ...load more sound
  562.  
  563.                 }
  564.              }
  565.  
  566.  
  567.  
  568.        ----------------------------------------------------------------
  569.        SndTbase
  570.        ----------------------------------------------------------------
  571.  
  572.        Function
  573.  
  574.              Sets the time base.
  575.  
  576.  
  577.        Syntax
  578.  
  579.              #include "sefx.h"
  580.              int SndTbase(int tbase);
  581.  
  582.  
  583.        Parameters
  584.  
  585.              tbase - Time base. This value determines the length of
  586.                      time of one tic and subsequently how often the
  587.                      frequency can be changed. Possibilities are:
  588.  
  589.                         LOW    (3) - 54.9 milliseconds
  590.                         MED    (2) - 27.5 milliseconds
  591.                         HIGH   (1) - 13.7 milliseconds
  592.                         ULTRA  (0) -  6.9 milliseconds
  593.  
  594.  
  595.        Remarks
  596.  
  597.              SndRes sets the time base. This value determines the
  598.              length of time of one tic, the basic unit of time used
  599.              by Sefx. Since a new tone can be loaded as often as once
  600.              per tic, the time base determines how often the frequency
  601.              can be changed.
  602.  
  603.  
  604.  
  605.        Return value
  606.  
  607.              SndTbase returns the previous time base.
  608.  
  609.  
  610.                                    10
  611.        See also
  612.  
  613.              SndOpen
  614.  
  615.  
  616.        Example
  617.  
  618.              Set the time base to 6.9 milliseconds per tic, later
  619.              restoring the original time base.
  620.  
  621.              {
  622.              int org_tb;
  623.  
  624.                 org_tb = SndTbase(ULTRA);
  625.  
  626.                    ... short tones
  627.              }
  628.  
  629.  
  630.              {
  631.  
  632.                    ... later
  633.  
  634.                 SndTbase(org_tb);
  635.  
  636.              }
  637.  
  638.  
  639.  
  640.        ----------------------------------------------------------------
  641.        SndFlush
  642.        ----------------------------------------------------------------
  643.  
  644.        Function
  645.  
  646.              Flushes all sound.
  647.  
  648.  
  649.        Syntax
  650.  
  651.              #include "sefx.h"
  652.              void SndFlush(void);
  653.  
  654.  
  655.        Remarks
  656.  
  657.              SndFlush flushes the sound queue, deleting all pending
  658.              and current sounds. It also terminates the current tone.
  659.  
  660.        See also
  661.  
  662.              SndLen SndTerm SndHold
  663.  
  664.  
  665.  
  666.  
  667.  
  668.  
  669.  
  670.  
  671.                                    11
  672.        Example
  673.  
  674.              Play a song after displaying the opening screen until
  675.              the user hits a key.
  676.  
  677.              {
  678.  
  679.                 ...display opening screen
  680.  
  681.                 SndString(song, 100, 0);
  682.  
  683.                 getch();
  684.  
  685.                 SndFlush();
  686.  
  687.                 ...continue
  688.  
  689.              }
  690.  
  691.  
  692.  
  693.        ----------------------------------------------------------------
  694.        SndHold
  695.        ----------------------------------------------------------------
  696.  
  697.        Function
  698.  
  699.              Puts all sound on hold or releases from hold.
  700.  
  701.  
  702.        Syntax
  703.  
  704.              #include "sefx.h"
  705.              int SndHold(int on_off);
  706.  
  707.  
  708.        Parameters
  709.  
  710.              on_off - hold on/off switch. Possibilities are
  711.  
  712.                          ON  (1) - put on hold
  713.                          OFF (0) - release from hold
  714.  
  715.        Remarks
  716.  
  717.              SndHold puts all sound on hold or releases it from a
  718.              previous hold condition. When a hold is set, the
  719.              current tone as well as the sound queue is immediately
  720.              frozen until it is subsequently released from hold.
  721.              When a hold condition is released, the sounds will
  722.              resume where it left off.
  723.  
  724.  
  725.        Return value
  726.  
  727.              SndHold returns the previous hold condition
  728.  
  729.  
  730.  
  731.  
  732.                                    12
  733.        See also
  734.  
  735.              SndFlush SndTerm
  736.  
  737.  
  738.        Example
  739.  
  740.              Make sure the sound is on hold temporarily and then
  741.              restore it to it's previous condition
  742.  
  743.              {
  744.              int prev_hold;
  745.  
  746.                 prev_hold = SndHold(ON);
  747.  
  748.                    ... guaranteed quiet time
  749.  
  750.                 SndHold(prev_hold);
  751.              }
  752.  
  753.  
  754.  
  755.        ----------------------------------------------------------------
  756.        SndTerm
  757.        ----------------------------------------------------------------
  758.  
  759.        Function
  760.  
  761.              Terminates the current sound.
  762.  
  763.  
  764.        Syntax
  765.  
  766.              #include "sefx.h"
  767.              void SndTerm(void);
  768.  
  769.  
  770.        Remarks
  771.  
  772.              SndTerm terminates the current sound. The sound may be a
  773.              single tone or many tones. In either case all the tones
  774.              that make up the sound are terminated.
  775.  
  776.  
  777.        See also
  778.  
  779.              SndFlush SndHold
  780.  
  781.  
  782.        Example
  783.  
  784.              Terminate the alarm when the user responds
  785.  
  786.              #define CONTINUOUS   0
  787.              #define Alarm()   SndTrill(1400, 600, 8, 8, CONTINUOUS)
  788.              {
  789.                 Alarm();
  790.                    ... wait for response
  791.                 SndTerm();
  792.              }
  793.                                    13
  794.        Sound Generation
  795.  
  796.        Sound generation functions load sounds into the sound queue to be
  797.        played in sequence. Most of the sound generation functions allow
  798.        the sound to be repeated a specified number of times or
  799.        continuously.
  800.  
  801.        A sounds consisting of a single tone is loaded with SndTone while
  802.        a sound consisting of a string of tones can be loaded with
  803.        SndString.
  804.  
  805.        Sefx provides sound generation functions for the more common types
  806.        of sounds. This includes trills, pulses and slides created by
  807.        the functions SndTrill, SndPulse and SndSlide respectively.
  808.        These basic sounds can create a multitude of sounds themselves and
  809.        in addition can be used with other sound generation functions to
  810.        create more complex combinations.
  811.  
  812.  
  813.  
  814.  
  815.  
  816.  
  817.  
  818.  
  819.  
  820.  
  821.  
  822.  
  823.  
  824.  
  825.  
  826.  
  827.  
  828.  
  829.  
  830.  
  831.  
  832.  
  833.  
  834.  
  835.  
  836.  
  837.  
  838.  
  839.  
  840.  
  841.  
  842.  
  843.  
  844.  
  845.  
  846.  
  847.  
  848.  
  849.  
  850.  
  851.  
  852.  
  853.  
  854.                                    14
  855.        ----------------------------------------------------------------
  856.        SndTone
  857.        ----------------------------------------------------------------
  858.  
  859.        Function
  860.  
  861.              Loads a single tone  into the sound queue.
  862.  
  863.  
  864.        Syntax
  865.  
  866.              #include "sefx.h"
  867.              void SndTone(int freq, int durtn);
  868.  
  869.  
  870.        Parameters
  871.  
  872.              freq  - frequency of the tone in hertz.
  873.  
  874.              durtn - number of tic the tone will last.
  875.  
  876.  
  877.        Remarks
  878.  
  879.              SndTone loads single tone of the specified frequency and
  880.              duration into the sound queue. Specifying a duration of 0
  881.              causes the tone to be played continuously. Specifying a
  882.              frequency of 0 will generate a pause. The single tone is
  883.              considered to be one sound.
  884.  
  885.        See also
  886.  
  887.              SndString SndPause SndTbase SndMs
  888.  
  889.  
  890.        Example
  891.  
  892.              Make a two second beep at 2000 hertz.
  893.  
  894.              {
  895.              int second;
  896.  
  897.                  ... made an error
  898.  
  899.                 second = SndMs(1000);
  900.                 SndTone(2000, 2*second);
  901.              }
  902.  
  903.  
  904.  
  905.  
  906.  
  907.  
  908.  
  909.  
  910.  
  911.  
  912.  
  913.  
  914.  
  915.                                    15
  916.        ----------------------------------------------------------------
  917.        SndPause
  918.        ----------------------------------------------------------------
  919.  
  920.        Function
  921.  
  922.              Loads a pause into the sound queue.
  923.  
  924.  
  925.        Syntax
  926.  
  927.              #include "sefx.h"
  928.              void SndPause(int durtn);
  929.  
  930.  
  931.        Parameters
  932.  
  933.              durtn - number of tics the tone will last
  934.  
  935.  
  936.        Remarks
  937.  
  938.              SndPause loads a pause (no sound) of the specified
  939.              duration into the sound queue. The pause is considered to
  940.              be one sound.
  941.  
  942.              SndPause is a function macro defined as SndTone(0, durtn).
  943.  
  944.  
  945.        See also
  946.  
  947.              SndTone SndTbase SndMs
  948.  
  949.  
  950.        Example
  951.  
  952.              Insert a three beat pause between two notes
  953.  
  954.              #define  A     440
  955.              #define  B     494
  956.              {
  957.              int beat;
  958.  
  959.                 beat = SndMs(500);
  960.  
  961.                 SndTone(A, 3*beat);
  962.                 SndPause(3*beat);
  963.                 SndTone(B, 3*beat);
  964.  
  965.              }
  966.  
  967.  
  968.  
  969.  
  970.  
  971.  
  972.  
  973.  
  974.  
  975.  
  976.                                    16
  977.        ----------------------------------------------------------------
  978.        SndString
  979.        ----------------------------------------------------------------
  980.  
  981.        Function
  982.  
  983.              Loads a string of tones into the sound queue.
  984.  
  985.  
  986.        Syntax
  987.  
  988.              #include "sefx.h"
  989.              void SndString(const TONE *str, int count, unsigned reps);
  990.  
  991.  
  992.        Parameters
  993.  
  994.              str    - pointer to an array of type TONE were the
  995.                       string of tones are stored.
  996.  
  997.              count  - number of tones in the array.
  998.  
  999.              reps   - number of times to repeat the string of
  1000.                       tones.
  1001.  
  1002.  
  1003.        Remarks
  1004.  
  1005.              SndString loads an string of tones, stored in an array
  1006.              of type TONE, into the sound queue. The string of tone
  1007.              will be repeated as specified. Specifying a repetition of
  1008.              0 will cause the string to be repeated continuously.
  1009.  
  1010.              The string of tones is considered to be one sound.
  1011.  
  1012.        See also
  1013.  
  1014.              SndTone SndTbase SndMs SndPause
  1015.  
  1016.  
  1017.        Example
  1018.  
  1019.              Play the scale of notes one time.
  1020.  
  1021.              #define  C     262
  1022.              #define  D     294
  1023.              #define  E     330
  1024.              #define  F     349
  1025.              #define  G     392
  1026.              #define  A     440
  1027.              #define  B     494
  1028.  
  1029.              {
  1030.              TONE scale[7] = { {C,3},{D,3},{E,3},{F,3},
  1031.                                {G,3},{A,3},{B,3}
  1032.                              };
  1033.  
  1034.                 SndString(scale, 7, 1);
  1035.              }
  1036.  
  1037.                                    17
  1038.        ----------------------------------------------------------------
  1039.        SndTrill
  1040.        ----------------------------------------------------------------
  1041.  
  1042.        Function
  1043.  
  1044.              Loads a trill sound into the sound queue.
  1045.  
  1046.  
  1047.        Syntax
  1048.  
  1049.              #include "sefx.h"
  1050.              void SndTrill(int freq1, int freq2,
  1051.                                       int durtn1, int durtn2, int reps);
  1052.  
  1053.  
  1054.        Parameters
  1055.  
  1056.              freq1  - frequency of the first tone in hertz.
  1057.  
  1058.              freq2  - frequency of the second tone in hertz.
  1059.  
  1060.              durtn1 - number of tics the first tone will last.
  1061.  
  1062.              durtn2 - number of tics the second tone will last.
  1063.  
  1064.              reps   - number of times to repeat the trill sound.
  1065.        Remarks
  1066.  
  1067.              SndTrill loads a trill sound into the sound queue. The
  1068.              trill is repeated as specified. Specifying a repetition
  1069.              of 0 will cause the trill to be repeated continuously.
  1070.  
  1071.              A trill sound is sometimes referred to as a flip-flop sound.
  1072.  
  1073.  
  1074.        See also
  1075.  
  1076.              SndSlide SndPulse SndMs SndTbase
  1077.  
  1078.  
  1079.        Example
  1080.  
  1081.              Make a telephone ring five times.
  1082.  
  1083.              {
  1084.              int i = 5;
  1085.  
  1086.                 while(i--)
  1087.                 {
  1088.                    SndTrill(1400, 600, 1, 1, 10);
  1089.                    SndPause(22);
  1090.                 }
  1091.              }
  1092.  
  1093.  
  1094.  
  1095.  
  1096.  
  1097.  
  1098.                                    18
  1099.        ----------------------------------------------------------------
  1100.        SndSlide
  1101.        ----------------------------------------------------------------
  1102.  
  1103.        Function
  1104.  
  1105.              Loads sliding tones into the sound queue.
  1106.  
  1107.  
  1108.        Syntax
  1109.  
  1110.              #include "sefx.h"
  1111.              void SndSlide(int start, signed dfreq,
  1112.                                                int durtn, int reps);
  1113.  
  1114.        Parameters
  1115.  
  1116.              start - frequency of the starting tone in hertz.
  1117.  
  1118.              dfreq - change (delta) in frequency per tic.
  1119.  
  1120.              durtn - number of tic the slide will last.
  1121.  
  1122.              reps  - number of times to repeat the slide.
  1123.  
  1124.  
  1125.        Remarks
  1126.  
  1127.              SndSlide loads sliding tones into the sound queue. The
  1128.              frequency is increased (positive 'dfreq') or decreased
  1129.              (negative 'dfreq') on each tic by the specified delta
  1130.              frequency. The sliding tone will last the specified
  1131.              duration and will be repeated as specified.
  1132.  
  1133.              To calculate the frequency of the ending tone in the slide
  1134.              use: end = start + (durtn - 1) * dfreq.
  1135.  
  1136.              Hint: shorter (faster) time bases generate a smoother
  1137.              sounding slide while longer (slower) time bases generate
  1138.              a more course sounding slide. Both cases can be useful
  1139.              for creating the desired effect.
  1140.  
  1141.        See also
  1142.  
  1143.              SndTrill SndPulse SndMs SndTbase
  1144.  
  1145.  
  1146.        Example
  1147.  
  1148.              Play a sliding tone from 2000 hertz to 992 hertz
  1149.  
  1150.  
  1151.              {
  1152.  
  1153.                 SndSlide(2000, -28, 37);
  1154.  
  1155.              }
  1156.  
  1157.  
  1158.  
  1159.                                    19
  1160.        ----------------------------------------------------------------
  1161.        SndPulse
  1162.        ----------------------------------------------------------------
  1163.  
  1164.        Function
  1165.  
  1166.              Loads a pulsing sound into the sound queue.
  1167.  
  1168.        Syntax
  1169.  
  1170.              #include "sefx.h"
  1171.              void SndPulse(int freq, int durtn,
  1172.                                              int pdurtn, int reps);
  1173.  
  1174.        Parameters
  1175.  
  1176.              freq   - frequency of the tone in hertz.
  1177.  
  1178.              durtn  - number of tics the tone will last.
  1179.  
  1180.              pdurtn - number of tics the pause will last.
  1181.  
  1182.              reps   - number of times to repeat the pulse.
  1183.  
  1184.  
  1185.        Remarks
  1186.  
  1187.              SndPulse loads a tone of the specified frequency and
  1188.              duration, followed by a pause of the specified duration
  1189.              The sound is repeated as specified. Specifying a repetition
  1190.              of 0 will cause the pulse to repeat continuously.
  1191.  
  1192.              SndPulse is a function macro defined as:
  1193.              SndTrill(freq, 0, durtn, pdurtn, reps);
  1194.  
  1195.  
  1196.        See also
  1197.  
  1198.              SndTrill SndSlide SndMs SndTbase
  1199.  
  1200.  
  1201.        Example
  1202.  
  1203.              Make a wrist watch alarm. (Time base = LOW/54.9)
  1204.  
  1205.              {
  1206.              int i = 3;
  1207.  
  1208.                 while(i--)
  1209.                 {
  1210.                    SndPulse(4250, 2, 1, 3);
  1211.                    SndPause(9);
  1212.                 }
  1213.  
  1214.              }
  1215.  
  1216.  
  1217.  
  1218.  
  1219.  
  1220.                                    20
  1221.        ----------------------------------------------------------------
  1222.        SndMs
  1223.        ----------------------------------------------------------------
  1224.  
  1225.        Function
  1226.  
  1227.              Converts milliseconds to tics.
  1228.  
  1229.  
  1230.        Syntax
  1231.  
  1232.              #include "sefx.h"
  1233.              int SndMs(unsigned ms);
  1234.  
  1235.  
  1236.        Parameters
  1237.  
  1238.              ms - number of milliseconds to convert to tics
  1239.  
  1240.  
  1241.        Remarks
  1242.  
  1243.              SndMs converts a value in milliseconds to the equivalent
  1244.              number of tics, rounding off to the nearest tic. SndMs
  1245.              takes into account the current time base and adjusts
  1246.              the resulting number of tics accordingly. The number of
  1247.              tics will always be at least one unless 0 milliseconds is
  1248.              specified.
  1249.  
  1250.              Shorter (faster) time bases result in a more precise
  1251.              conversion than longer (slower) time bases. In most
  1252.              applications this is an insignificant limitation. In
  1253.              any case the value will never be off more that the length
  1254.              of time of one tic.
  1255.  
  1256.  
  1257.        Return value
  1258.  
  1259.              SndMs returns the number of tics that is approximately
  1260.              equal to the specified number of milliseconds.
  1261.  
  1262.  
  1263.        See also
  1264.  
  1265.              SndTbase
  1266.  
  1267.  
  1268.        Example
  1269.  
  1270.              Make a one second tone at 100 hertz
  1271.  
  1272.              {
  1273.              int second;
  1274.  
  1275.                 second = SndMs(1000);
  1276.  
  1277.                 SndTone(100, second);
  1278.  
  1279.              }
  1280.  
  1281.                                    21
  1282.         Appendix A
  1283.  
  1284.  
  1285.        Things to look out for.
  1286.  
  1287.        ∙ Sefx takes over interrupt 8 and may change the system clock
  1288.          rate. If the clock rate is changed, Sefx arbitrates the
  1289.          timer chain in order that it's rate remains the same. If
  1290.          a program written with Sefx needs to chain into interrupt 8
  1291.          it should do so prior to the calling SndOpen.
  1292.  
  1293.        ∙ The functions SndOpen and SndClose make calls to the C
  1294.          functions malloc and free respectively.
  1295.  
  1296.        ∙ In the small and medium memory models, the near heap where
  1297.          the sound queue is allocated, is limited. The data segment
  1298.          (globals etc.) + the stack + allocated memory (sound queue)
  1299.          must not exceed 64K bytes. If an extremely large sound queue
  1300.          is required the compact or large model, where the sound queue
  1301.          can be as large as 65532 bytes, should be used.
  1302.  
  1303.  
  1304.  
  1305.  
  1306.  
  1307.  
  1308.  
  1309.  
  1310.  
  1311.  
  1312.  
  1313.  
  1314.  
  1315.  
  1316.  
  1317.  
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324.  
  1325.  
  1326.  
  1327.  
  1328.  
  1329.  
  1330.  
  1331.  
  1332.  
  1333.  
  1334.  
  1335.  
  1336.  
  1337.  
  1338.  
  1339.  
  1340.  
  1341.  
  1342.                                    22
  1343.        Appendix B
  1344.  
  1345.        Musical notes.
  1346.  
  1347.        This appendix provides information about frequencies of musical
  1348.        notes and octave shifting.
  1349.  
  1350.  
  1351.        The Equal Tempered Chromatic Scale (rounded to integer)
  1352.  
  1353.           note|freq  |  note|freq  |  note|freq  |  note|freq
  1354.         -------------|-------------|-------------|-------------
  1355.           C0     16  |  C2     65  |  C4    262  |  C6   1047
  1356.           C#0    17  |  C#2    69  |  C#4   277  |  C#6  1109
  1357.           D0     18  |  D2     73  |  D4    294  |  D6   1175
  1358.           D#0    19  |  D#2    78  |  D#4   311  |  D#6  1245
  1359.           E0     21  |  E2     82  |  E4    330  |  E6   1319
  1360.           F0     22  |  F2     87  |  F4    349  |  F6   1397
  1361.           F#0    23  |  F#2    93  |  F#4   370  |  F#6  1480
  1362.           G0     25  |  G2     98  |  G4    392  |  G6   1568
  1363.           G#0    26  |  G#2   104  |  G#4   415  |  G#6  1661
  1364.           A0     28  |  A2    110  |  A4    440  |  A6   1760
  1365.           A#0    29  |  A#2   117  |  A#4   466  |  A#6  1865
  1366.           B0     31  |  B2    123  |  B4    494  |  B6   1976
  1367.                      |             |             |
  1368.           C1     33  |  C3    131  |  C5    523  |  C7   2093
  1369.           C#1    35  |  C#3   139  |  C#5   554  |  C#7  2217
  1370.           D1     37  |  D3    147  |  D5    587  |  D7   2349
  1371.           D#1    39  |  D#3   156  |  D#5   622  |  D#7  2489
  1372.           E1     41  |  E3    165  |  E5    659  |  E7   2637
  1373.           F1     44  |  F3    175  |  F5    698  |  F7   2794
  1374.           F#1    46  |  F#3   185  |  F#5   740  |  F#7  2960
  1375.           G1     49  |  G3    196  |  G5    784  |  G7   3136
  1376.           G#1    52  |  G#3   208  |  G#5   831  |  G#7  3322
  1377.           A1     55  |  A3    220  |  A5    880  |  A7   3520
  1378.           A#1    58  |  A#3   233  |  A#5   932  |  A#7  3729
  1379.           B1     62  |  B3    247  |  B5    988  |  B7   3951
  1380.                                                  |  C8   4186
  1381.  
  1382.        Since the frequencies of the octaves increase as a factor of
  1383.        two, musical notes of the other octaves are easily accomplished
  1384.        by multiplying or dividing by factors of two, or more
  1385.        efficiently by shifting left or right. For example to obtain
  1386.        the frequency of A5, the value of A4 (440) is shifted left
  1387.        once (multiplied by two). To obtain the frequency of A2,
  1388.        shift A4 right twice (divide by four).
  1389.  
  1390.        Examples:   A5 = A4 << 1
  1391.  
  1392.                    A2 = A4 >> 2
  1393.  
  1394.        Note: It is better to shift from a higher octave to a lower
  1395.        octave since the percent of rounding error, when rounding to an
  1396.        integer, is smaller with the larger values.
  1397.        Appendix C
  1398.  
  1399.  
  1400.  
  1401.  
  1402.  
  1403.                                    23
  1404.        Appendix C
  1405.  
  1406.        Sound queue usage
  1407.  
  1408.        Some of the sound generation functions load instructional
  1409.        information as well as frequency and duration information. This
  1410.        added information allows Sefx to conserve memory. When the sound
  1411.        is initially loaded by the sound generation function, it will
  1412.        occupy an 'initial' number of bytes in the sound queue. When the
  1413.        next sound is fetched from the sound queue, the instructional
  1414.        information is evaluated and then discarded. The remaining bytes
  1415.        will continue to occupy the sound queue until the sound is
  1416.        terminated. This is referred to in the table below as 'residual'.
  1417.  
  1418.  
  1419.                               Initial           Residual
  1420.                              ---------         ----------
  1421.  
  1422.           SndTone                4                 4
  1423.  
  1424.           SndPause               4                 4
  1425.  
  1426.           SndString         8 + 4 * len         4 * len
  1427.  
  1428.           SndTrill              16                 8
  1429.  
  1430.           SndSlide         8 + 4 * durtn       4 * durtn
  1431.  
  1432.           SndPulse              16                 8
  1433.  
  1434.  
  1435.  
  1436.  
  1437.  
  1438.  
  1439.  
  1440.  
  1441.  
  1442.  
  1443.  
  1444.  
  1445.  
  1446.  
  1447.  
  1448.  
  1449.  
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.  
  1457.  
  1458.  
  1459.  
  1460.  
  1461.  
  1462.  
  1463.  
  1464.                                    24
  1465.        Appendix D
  1466.  
  1467.        Sefx v1.0 Registration Form
  1468.  
  1469.        Name: ______________________________________________________
  1470.  
  1471.        Company: ___________________________________________________
  1472.  
  1473.        Address: ___________________________________________________
  1474.  
  1475.        City: ____________________________  State: _________________
  1476.  
  1477.        Zip code: _________________  Phone # : _____________________
  1478.  
  1479.        CompuServe # : _____________________________________________
  1480.  
  1481.        How did you acquire Sefx ? _________________________________
  1482.  
  1483.        ____________________________________________________________
  1484.  
  1485.        What functions do you find most useful ?____________________
  1486.  
  1487.        ____________________________________________________________
  1488.  
  1489.        What functions do you find least useful ?___________________
  1490.  
  1491.        ____________________________________________________________
  1492.  
  1493.        What functions, not in Sefx, would you like to see ?________
  1494.  
  1495.        ____________________________________________________________
  1496.  
  1497.        What other types of libraries would you find useful ?_______
  1498.  
  1499.        __ Serial Communications  __ Expanded Memory  __ IEEE/GPIB
  1500.  
  1501.        __ Game Port  Others: ______________________________________
  1502.  
  1503.        registration                                      $ 20.00
  1504.  
  1505.        California residents add sales tax (  8.25% )     $________
  1506.  
  1507.        shipping inside continental U.S.   ( $ 2.00 )
  1508.        shipping outside continental U.S.  ( $ 5.00 )     $________
  1509.  
  1510.  
  1511.                                                 Total:   $________
  1512.  
  1513.        All Payments Must be in U.S. Dollars
  1514.  
  1515.        Make check or money order payable to:    Bri Productions
  1516.                                                 P.O. Box 7121
  1517.                                                 Fremont, CA 94537-7121
  1518.  
  1519.  
  1520.  
  1521.  
  1522.  
  1523.  
  1524.  
  1525.                                    25
  1526.